"= LiMo Foundation" 


Event Delivery Foundation API 


Version 1.0 
March 6, 2008 


PLEASE REVIEW THE TERMS OF THE FOUNDATION API LICENSE VERSION 1.0 
BEFORE READING THIS DOCUMENT. 


You may view the Foundation API License v1.0 at: 


http://www.limofoundation.org/images/stories/pdf/limo foundation api license vl-0.pdf 


This is an agreement between you (“You”) and LiMo Foundation related to the use of the APIs contained 
within this document. By accessing, downloading, reading or otherwise using the APIs contained within 
this document, You accept the terms of the Foundation API License v1.0. If You do not agree to the terms 
of this agreement, do not download, read and/or otherwise use any of the APIs. 


If You are agreeing to be bound by the Foundation API License v1.0 on behalf of your employer, You 
represent and warrant that you have full legal authority to bind your employer to this agreement. If You 
do not have the requisite authority, You may not download, read and/or otherwise use any of the APIs on 
behalf of your employer. 


© Copyright LiMo Foundation 2007, 2008. All rights reserved. 


NOTICES 


This document and the technical information it contains is subject to change by LiMo Foundation and 
its members at any time without notice as authorized by LiMo Foundation bylaws and other documents 
governing LiMo Foundation, including amendments thereto. All statements regarding LiMo’s future 
direction or intent are subject to change or withdrawal without notice, and represent goals and objectives 
only. 


Any reference in this document to non-LiMo Foundation Web sites do not in any manner serve as an 
endorsement of those Web sites. The materials at those Web sites are not part of this document or any 
product described in this document and use of those Web sites is at your own risk. 


Information concerning non-LiMo products was obtained from the suppliers of those products or a public 
announcement or source. LiMo cannot confirm the accuracy of that information or the performance, 
compatibility or any other claims related to non-LiMo products. 


All names or other identifying information used in examples in this document are fictitious and any 
similarity to the names or other identifying information of an actual person or organization is entirely 
coincidental. 


THIS DOCUMENT AND ALL INFORMATION IN THIS DOCUMENT ARE PROVIDED “AS IS”, 
WITHOUT ANY EXPRESS OR IMPLIED WARRANTY OR CONDITION, INCLUDING, BUT 
NOT LIMITED TO, ANY WARRANTY OR CONDITION OF ACCURACY OR COMPLETENESS, 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR AGAINST INFRINGEMENT. 
ALL EXPRESS AND IMPLIED STATUTORY WARRANTIES ARE DISCLAIMED, INCLUDING 
WITHOUT LIMITATION, THE WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICU- 
LAR PURPOSE, TITLE OR NON-INFRINGEMENT. 


© Copyright LiMo Foundation 2007, 2008. All rights reserved. 


Contents 


1 Event Delivery Foundation API 1 
LI AIN 1 
E eee sr NA 1 
13 sr Sind. a a A RG de ak a as 1 
1,4. Extemal API Documents +... orcas a ee EG 1 
US Plougin Extensión Point Intertice... 2.0.24 eae See GE EKG A e 1 
LO Other IESE a ee A be oe Ra a eR ee es 2 
L? Oiber Noies o a e ew eA eir a waa Pe ae ee a eH E a 2 

2 Module Index 3 
BT Modules ce ar ea i BAO a e Fare eke dá 3 

3 Class Index 5 
GE Class LIRE ia ha eee a ee Pee a a 3 

4 File Index 7 
AT Rule Lage = reui ea ee oe e oe A oe RA a eS 7 

5 Module Documentation 9 
SI Event Adaplet...2...544 se ben 66845084 64044 530 HAS SE ea 9 
52. Event Delivery Detailed Description. s -sps 625 Sse ee se Mee SS SC ER Rw 10 
KE GE A Skea aed abe Ge ee oh ee ae es Ee 16 
3A Code Examples oe oo... bec ee ea dk Jet ÅGE Gr eeo ee ee d 21 

6 Class Documentation 25 
6.1 CEvtSysEventAdapter Class Reference ....... o... o... +... 0222000. 25 
6.2 ExvtSysEventProperty_t Struct Referente . cos... .< sruma tg niesek 29 
6.3 EvtSysEventSourceld_t Struct Reference .......... +... . eee eee ene 31 


7 File Documentation 33 


CONTENTS 


7.1 


ComponentOverview.h File Reference 


A Re egos DE See 33 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


Chapter 1 


Event Delivery Foundation API 


1.1 References 


[1] Software Architecture Document, Version 1.1 Revision 1.4, LiMo Foundation, 11 September 2007 


[2] LiMo Foundation, Frequently Asked Questions, "LiMo Foundation", 
<http://www.limofoundation.org/faqs/index.php>,27 December 2007 


[3] Application Launcher Foundation API, Version 1.0, LiMo Foundation, 25 January 2008 


[4] freedesktop.org, Documentation, "freedesktop.org - Software/dbus",<http://www.freedesktop.org/wiki/Soft 
4 January 2008 


1.2 Overview 


Event Delivery is responsible for publication of messages to arbitrary number of subscribers that enables 
applications to be aware of surrounding environment and take corresponding action accordingly. Event 
Delivery provides means of generating, processing, filtering, subscribing, publishing system-wide and 
application-specific notifications. 


Å message which Event Delivery handles is expressed as an event and some data. 


1.3 Industry Standard 


None 


1.4 External API Documents 


None 


1.5 Plug-in Extension Point Interface 


None 


2 Event Delivery Foundation API 


1.6 Other Interfaces 


None 


1.7 Other Notes 


The API of class CEvtSysEventAdapter is part of the Event Delivery Framework API. 
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Module Index 


2.1 Modules 


Here is a list of all modules: 


Event Adapters å as sad se sat Se pe EP be Rab e Rs SEG 9 
Event Delivery Detailed Description ........ o... . 0... 0000000000000. 10 
Event DEUVvery uo Suda i klage Ge Rel or See oe SRG Ses 16 


Code: Examples: e sgp e te es se Sud se KE GS GEAR SØTESTE Hee ESS 21 


Module Index 
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Chapter 3 


Class Index 


3.1 Class List 


Here are the classes, structs, unions and interfaces with brief descriptions: 


CEvtSysEventAdapter (An Adapter for a legacy system should inherit this class and inherit its 

pure virtual functions) ................ e 25 
a E s «i.e et cea oe ee ERE Se ee ene 29 
EviSysEventSowrceld t oos coro aa a ER EER HR RE a a nå 31 


Class Index 
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Chapter 4 


File Index 


4.1 File List 


Here is a list of all documented files with brief descriptions: 


ComponentOverview.h (Component Programming Interface Overview Header Template for 
Doxygen) 2 eo et ene ee a di Eo hake ROBA A 


File Index 
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Module Documentation 


5.1 Event Adapter 


5.1.1 Event Adapter 


Event Adapter is a component that converts messages from legacy systems to LiMo events and vice versa. 
Interfaces of legacy systems are in diverse forms, e.g. pipe, socket, etc, but they all should be file descriptor- 
based. Messages from legacy systems are published in form of LiMo events and vise-versa.Adapter sends 
Events in asynchronous manner. 


10 Module Documentation 


5.2 Event Delivery Detailed Description 


5.2.1 Event Delivery 
5.2.1.1 Event Delivery 


ED (Event Delivery) is for managing events between system to application or application to application. 
ED is implemented using DBus that is a message bus system, a simple way for applications to talk to one 
another. 


5.2.1.2 publish-Subscribe Model 


ED employs Publish-Subscribe model to decouple event sender and receiver. In this model, subscriber says 
to an intermediary broker that it wants to receive specific set of events. When publisher publishes one of 
the events, broker delivers it to all subscribers of this event. ED acts as a broker in this model. 


5.2.1.3 Event ID and Event Property 


Event consists of Event ID and arbitrary number of Properties. Event ID is a string that is hierarchi- 
cally structured, e.g., "System.State.Clamshell.Opened". Event Properties are event-specific information, 
e.g., Event ID "Test.Power.BatteryLevel.Changed" has two Properties "BetteryLevel" and "Connected- 
ToCharger". 


5.2.1.4 Event Filter 


The Event Filter is used to selectively receive Events based on its Properties. An example of filter expres- 
sion is "BatteryLevel < 15 and ConnectedToCharger = false". 


5.2.1.5 Synchronous Event and Asynchronous Event 


Events are classified into two categories: Synchronous and Asynchronous. The former is a blocking oper- 
ation that publisher is waiting for all subscribers to handle the event. An example of Synchronous Event 
is "System.UITheme.Changed" that the publisher has to wait for all the subscribers to change its theme. 
The latter is non-blocking that publisher sends event and returns immediately. It doesn’t care about event 
handling. Most of the events fall into this category. 


Whether an Event is synchronous or asynchronous is an attribute of Event, not of Subscription. 
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i l:noti pobliah _ | 

| 2:Publishevent _ | 

3 : Call event callback) 
€ rnmennennemnsmeed 4: Return ; 

¡O 5; Retum 


Figure 5.1: Publishing Synchronous Event 


1 : moti_publish() 


E ER EEE ene 
i 2 i Return i 3 : Publish event 


| 4 ; Call event callback() 


Figure 5.2: Publishing Asynchronous Event 


5.2.1.6 Auto-Activation 


Limo ED supports application Auto-Activation feature in order to ensure delivery of Event even if sub- 
scriber application is not running. It exploits the DBus auto-activation mechanism. When an application is 
being installed, it can be configured to be auto-activated in response to a specific Event. When the Event is 
published, ED requests AL (Application Launcher) to launch the subscriber application and when it finishes 
launching, the temporarily-held Event is forwarded. This useful feature alleviates publisher application’s 
concern so that it doesn’t have to consider subscriber application’s state. 
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Application 1 ED AL Application 2 


| 1 : noti-open() 


: noti-publish() 


3 : "publishing an event" 


4: If app not running ? 


at 
[] 5: “launch the app": 


AY 


i 6 : "app model: Application launch" h 
| 7 : noti-open(} 


8 : noti-subscribe() 


i : 9; “subscribing For an event” r 


10: "subscription successful" 


11 : "event delivered" : 


1 12: call event callback() 


13: return 


194 
[] 14 : return. 


Figure 5.3: Auto Activation 


5.2.2 Registering/Unregistering an Event 


Currently registration/unregistration of an event is done using a command line tool : event-tool. 
* Registering an Event : 


set-event-info event id sync or async [prop name prop data type]... 


Registers Event Information and sync/async and properties and data types of properties. 


* event id Event ID. 

e sync or async s for synchronous Event. as for asynchronous Event. 

* prop name Property name. 

* prop data type Property data type. Must be one of int, double, bool or string. 


Example : event-tool set-event-info Event ID s(as) Propertynamel PropertyDataTypel Propertyname2 
PropertyDataType2 ... 


e Un-registering an Event : 


unset-event-info event id 
Unregisters Event Information of event id. 


In order to use an event it has to be registerd with ED in advance. Note : Wildcards are not allowed in the 
registration. 
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5.2.3 Filter Syntax 


When subscribing to Event, application can specify Filter expression for describing filter criteria on Event’s 
properties. Filter expression is a typical conditional statement composed of operands and operator. It 
should have at least one Event’s property name as operand. We support following syntax for operands and 
operators. 


OPERANDS 

Operand can be either property name or value. 

Syntax of property name 

1. Sequence of alphabetical characters([a-zA-Z]), digits([0-9]) and underscore character(_) is allowed. 
2. Starting character should always be alphabetical character. 

3. Data type of represented property name could be either integer, double, boolean or string. 

Syntax of values 

I Numerical expression 

1. Integer 

. Digits [0-9] 


2 


b. -(minus) is used for negative values 
. Double 
. Digits [0-9] 


= 


pao] 


b. -(minus) is used for negative values 
c. .(dot) is used as decimal symbol 
II Literal expression 


1. String : Use double quotes or single quotes in order to specify string literal. Escape character is allowed 
for specifying string literal in several lines. For example, following is allowed for specifying String literal 
example literal as string type operand. 


e "String literal example" 


e "String literal example” 


e "String literal \ 
example" 
* "String literal \ 


example’ 

III Boolean expression 
TRUE(true, True) 
FALSE(false, False) 
OPERATORS 

1. Unary Operator 


Boolean Operator : NOT; Only boolean operands are allowed 
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Unary minus ;For negative numerical expression 

Unary plus ; For positive numerical expression 

2. Binary Operator 

Boolean Operator : AND, OR ;Only boolean operands are allowed. 
Comparison Operator =, <>, <, <=, >, >= 


Integer, double and string type operands are allowed for all comparison operators.Numerical 
operands(integer, double) can be compared only between numerical operands.Literal operands can be com- 
pared only between literal operands 


Boolean operands are allowed for =, != operators. Boolean operands can be compared only between 
boolean operands 


3. Arithmetic Operator :+, -, *, /,% 
Only integer and double type operands are allowed 
4. String Operator : LIKE 


String operation returns boolean result for whether (1) certain string type property name starts with, (2) 
certain string type property name contains, (3) certain string type property name ends with certain string. 
This operation is specified by using LIKE operator and percentage symbol. 


"%" symbol is only allowed to appear in front or end of string literal which is second operand of LIKE 
operator. Note that "%" is not a general wildcard mark. These three kinds of string operation can be 
specified as following examples. Assume DbFileName is property name of certain Event whose data type 
is string. 


e DbFileName LIKE ’abc%’ 

This operation returns true if DbFileName starts with "abc" string 
e DbFileName LIKE ’%abc%’ 

This operation returns true if DbFileName contain "abc" string 
e DbFileName LIKE ’%abc’ 


This operation returns true if DbFileName end with "abc" string 
— Parenthesis : (, ) 


Some examples for valid and invalid filter expressions. Assume following property names are defined, 


* BatteryLevel : integer type property 
e OldBatteryLevel, NewBatteryLevel : double type property 


e ConnectedToCharger : boolean type property 


Valid Filter Expressions: 

1. "BatteryLevel < 10" 

2. "OldBatteryLevel < (5 + NewBatteryLevel)" 

3. "(BatteryLevel < 10) AND (ConnectedToCharger = false)" 
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Invalid Filter Expression 


1. "BatteryLevel > true" 


* Reason : boolean operand(true) not allowed for comparison operator > 


2."OldBatteryLevel < (5 + ConnectedToCharger)" 


* Reason : boolean operand(ConnectedToCharger) not allowed for arithmetic operator + 


3. "(BatteryLevel < 10) AND (5 + NewBatteryLevel)" 


* Reason : Only boolean type operands are allowed for boolean operator AND ( result of arithmetic 
operation is not boolean) 
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5.3 Event Delivery 


Classes 


* struct EvtSysEventProperty_t 
* struct EvtSysEventSourceld t 


Error codes 


e enum EvtSysErrorEvent t I 


EVTSYS ERROR EVENT GCONF GET VALUE = -1, EVTSYS ERROR EVENT GCONF - 
SET VALUE = -2, EVTSYS ERROR EVENT INFO = -3, EVTSYS ERROR EVENT - 
INVALID ARG = -4, 


EVTSYS ERROR EVENT INVALID EVENT ID = -5, EVTSYS ERROR EVENT - 
INVALID SUBSCRIPTION ID = -6, EVTSYS ERROR EVENT FILTER NOT ALLOWED - 
WITHOUT PROPERTY = -7, EVTSYS ERROR EVENT FILTER NOT ALLOWED FOR - 
EVENT GROUP = -8, 


EVTSYS ERROR EVENT FILTER EVALUATE = -9, EVTSYS ERROR EVENT INVALID - 
HANDLE = -10, EVTSYS ERROR EVENT INTERNAL TANSPORT = -11 } 


Typedefs 


e typedef bool(* EvtSysEventCb XEvtSysEventSourceld tsre id, const char «event id, const GArray 
*event properties, void *priv data) 


Functions 


int EvtSysLibraryOpen (int *handle,) 

int EvtSysEventSubscribe (int handle, const char xevent id, const char *filter expression, EvtSy- 
sEventCb callback, void *priv data, unsigned int *subscription id,) 

int EvtSysEventUnsubscribe (int handle, unsigned int subscription id,) 

int EvtSysEventPublish (int handle, const char xevent id....) 

int EvtSysLibraryClose (int handle,) 


5.3.1 Typedef Documentation 


5.3.1.1 typedef bool(« EvtSysEventCb)(EvtSysEventSourceld_t src_id, const char xevent id, const 
GArray xevent properties, void «priv_data) 


Prototype of Event handler. 


Parameters: 
[IN] src_id Event Source ID 
[IN] event_id Event ID.ED will send event ID string in this parameter. 


[IN] event_properties Array (GArray) of EvtSysEventProperty_t. GArray is a struct from GLib that 
can contain arbitrary number of elements. 


[IN] priv_data Generic pointer that has been set when subscribing to an Event. 
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Returns: 


return true on success 


5.3.2 Enumeration Type Documentation 


5.3.2.1 enum EvtSysErrorEvent t 


Enumerator: 


EVTSYS ERROR EVENT GCONF GET VALUE GConf error occurred while trying to retrieve 
a value from GConf Registry. 


EVTSYS ERROR EVENT GCONF SET VALUE GConf error occurred while trying to set a 
value in GConf Registry. 
EVTSYS_ERROR_EVENT_INFO The value of an Event detail was found to be invalid. 


EVTSYS_ERROR_EVENT_INVALID_ARG Invalid arguments were found to be passed to a func- 
tion. 


EVTSYS_ERROR_EVENT_INVALID_EVENT_ID Invalid event ID. 


EVTSYS_ERROR_EVENT_INVALID_SUBSCRIPTION_ID Unsubscribe request for a subscrib- 
tion id not mapped to any event subscribed to. 


EVTSYS_ERROR_EVENT_FILTER_NOT_ALLOWED_WITHOUT_PROPERTY Filtering 
without any property is not allowed. 


EVTSYS ERROR EVENT FILTER NOT ALLOWED FOR EVENT GROUP Filtering is 
done based on one or more of the individual events” properties and thus while subscribing to a 
group of events filtering is not allowed. 


EVTSYS ERROR EVENT FILTER EVALUATE Error occurred during filter evaluation. 
EVTSYS ERROR EVENT INVALID HANDLE. The Handle to ED was found to be invalid 


EVTSYS ERROR EVENT INTERNAL TANSPORT Error occured while using the internal IPC 
mechanism 


5.3.3 Function Documentation 
5.3.3.1 int EvtSysEventPublish (int handle, const char event id,...) 


EvtSysEventPublish() publishes Event to all subscribers. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 
[IN] handle Handle to the ED. 
[IN] event_id Event ID of the event being published. 


T 


Parameters: 


[IN] ... Event Properties. The number of properties varies by each Event. 
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Returns: 


On success, zero is returned. On error, error_value is returned. Its value may be one of those mentioned 
under Exceptions 


Exceptions: 


EVTSYS_ERROR_EVENT_INVALID_HANDLE 
EVTSYS_ERROR_EVENT_INVALID_EVENT_ID 
EVTSYS_ERROR_EVENT_INTERNAL_TANSPORT 
EVTSYS_ERROR_EVENT_FILTER_EVALUATE 


5.3.3.2 int EvtSysEventSubscribe (int handle, const char x event id, const char x filter expression, 
EvtSysEventCb callback, void x priv_data, unsigned int x subscription. id) 


EvtSysEventSubscribe() subscribes to an Event or to a group of Events. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[IN] handle Handle to the ED. 


[IN] event_id Event ID. This is a string that represents an Event or a group of Events. Examples are 
"System.State.Clamshell.Opened" and "System.State.Clamshell.x". Note that when specifying 
an Event group, *(asterisk) is only allowed to appear after a dot. And after x nothing is allowed. 


[IN] filter_expression filter_expression is a conditional statement that controls receiving Event based 
on Event Property. An example of filter expression is "BatteryLevel < 5 and Connected- 
ToCharger = false". It should contain at least one Event Property Name. When the filter is 
not needed, pass NULL or empty string. 


[IN] callback Pointer to callback function which handles the Event. 


[IN] priv_data priv_data is a generic pointer that is passed to Event handler when it gets called on 
event publication. 


[OUT] subscription_id On successful subscription, ED will return Subscription ID in this pointer.This 
Subscription ID is to be used to un-subscribe from the event. 


Returns: 


On success, zero is returned. On error, error_value is returned. Its value may be one of those mentioned 
under Exceptions 


Exceptions: 


EVTSYS_ERROR_EVENT_INVALID_HANDLE 
EVTSYS_ERROR_EVENT_INVALID_EVENT_ID 
EVTSYS_ERROR_EVENT_INVALID_ARG 
EVTSYS_ERROR_EVENT_FILTER_NOT_ALLOWED_WITHOUT_PROPERTY 
EVTSYS_ERROR_EVENT_FILTER_NOT_ALLOWED_FOR_EVENT_GROUP 
EVTSYS_ERROR_EVENT_FILTER_EVALUATE 
EVTSYS_ERROR_EVENT_INTERNAL_TANSPORT 
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5.3.3.3 int EvtSysEventUnsubscribe (int handle, unsigned int subscription id) 


EvtSysEventUnsubscribe() unsubscribes a subscription specified by subscrption id. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 
[IN] handle Handle to the ED. 
[IN] subscription_id Subscription ID. 


Returns: 


On success, zero is returned. On error, error_value is returned. Its value may be one of those mentioned 
under Exceptions 


Exceptions: 


EVTSYS_ERROR_EVENT_INVALID_HANDLE 
EVTSYS_ERROR_EVENT_INVALID_SUBSCRIPTION_ID 
EVTSYS_ERROR_EVENT_GCONF_SET_VALUE 
EVTSYS_ERROR_EVENT_GCONF_GET_VALUE 
EVTSYS_ERROR_EVENT_INTERNAL_TANSPORT 


Remarks: 


You can unsubscribe only using the subscription ID returned at the time of subscription to the event. 


5.3.3.4 int EvtSysLibraryClose (int handle) 


EvtSysLibraryClose() closes connection to ED. When the connection is closed, all temporary subscription 
information is cleared. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[IN] handle Handle to the ED. 


Returns: 
On success, zero is returned. On error, error value is returned. Its value may be one of those mentioned 
under Exceptions 

Exceptions: 


EVTSYS ERROR EVENT INVALID HANDLE 
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5.3.3.5 int EvtSysLibraryOpen (int x handle) 


EvtSysLibraryOpen() gains a connection to ED. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[OUT] handle Handle to the ED. 


Returns: 


On success, zero is returned. On error, error_value is returned. Its value may be one of those mentioned 
under Exceptions 


Exceptions: 


EVTSYS_ERROR_EVENT_INTERNAL_TANSPORT 


Remarks: 


The ED maintains the context of an application based on this handle value returned thus. All other 
APIs require a valid handle as parameter. 
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5.4 Code Examples 


5.4.1 Publishing an Event 


* Here is an application that publishes Event "System.Power.BatteryLevel.Changed". 


tinclude <stdio.h> 
tinclude <limo-event-delivery.h> 


int main (int argc, char x**argv) 
{ 

int handle; 

int error_code; 


if ((error_code=EvtSysLibraryOpen (&handle))!=0 ) 
{ 
fprintf(stderr, O: S#X\n", error code); 
return error_code; 


if ((error code= EvtSysEventPublish ( 


handle, 

"Test.Power.BatteryLevel.Changed", // Event ID 
Br // BatteryLevel 

false))!=0 ) // ConnectedToCharger 


fprintf(stderr, "Error EvtSysEventPublish():%#X \n", error code); 


return error_code; 


if ((error_code= EvtSysLibraryClose (handle) ) !=0) 

{ 
fprintf(stderr, "Error event_finish(): %#X\n", error_code); 
return error_code; 


return 0; 


5.4.2 Subscribing to an Event 


Here is an application that subscribes to Event "System.Power.BatteryLevel.Changed". 


#include <stdio.h> 

#include <glib.h> 

#include <string.h> 

#include <limo-event-delivery.h> 


bool on_batterylevelchanged ( 
EvtSysEventSourceld_t src id, 
const char* event id, 
const GArrayx properties, 
voidx priv data) 


EvtSysEventProperty tx e; 


printf("Got Event %s from application (%d %d %s %s)\n", 
event id, src id.app id, src id.inst id, src id.namel, 


printf("priv data=%sYn", (charx) priv data); 


src_id.name2) ; 
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// Get properties 
e = &g_array_index (properties, EvtSysEventProperty_t, 0); 
printf ("Battery level = %d\n", e->value.i); 


e = &g_array_index (properties, EvtSysEventProperty_t, 1); 
printf ("Connected to charger = %s\n", e->value.b ? "T" : "F"); 


// We've done with this Event 
return true; 


int main (int argc, char xxargv) 


GMainLoop* mainloop; 

int handle; 

unsigned int subscription_id; 

int error_code; 

char* priv data = "First subscription"; 


if ((error code= EvtSysLibraryOpen(&handle) !=0) 

{ 
fprintf(stderr, "Error EvtSysEventInit ():%#X \n", error code); 
return error_code; 


if ((error_code= EvtSysEventSubscribe ( 


handle, 
"Test .Power.BatteryLevel.Changed", // Event ID 
"(BatteryLevel < 10) and (ConnectedToCharger = false)",// Filter expression 
on_batterylevelchanged, // Event handler 
(voids) priv data, // Priv data 
&subscription id))!=0) // Subscription ID 

{ 

fprintf(stderr, "Error EvtSysEventSubscribe():%#X \n", error code); 


return error_code; 


mainloop = g_main_loop_new(NULL, FALSE); 
g_main_loop_run(mainloop) ; 


if ((error_code= EvtSysLibraryClose (handle, &error_code) ) !=0) 

{ 
fprintf(stderr, "Error: event_finish() %#X\n", error code); 
return error_code; 


return 0; 


5.4.3 Unsubscribing to an Event 


Here is an application that unsubscribes to Event "System.Power.BatteryLevel.Changed". 


#include <stdio.h> 
#include <glib.h> 
#include <limo-event-delivery.h> 


int main (int argc, char xxargv) 
{ 
int handle; 
unsigned int subscription_id; 
int error_code; 
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if ((error_code= EvtSysLibraryOpen(&handle) !=0) 

{ 
fprintf(stderr, "Error EvtSysEventInit ():%#X \n", error code); 
return error_code; 


if ((error_code= EvtSysEventUnsubscribe ( 


handle, subscription_id))!=0) // Subscription ID 
{ 
fprintf(stderr, "Error EvtSysEventSubscribe():%#X \n", error_code); 


return error_code; 


if ((error_code= EvtSysLibraryClose(handle, &error_code) ) !=0) 

{ 
fprintf(stderr, "Error: event_finish() %#X\n", error code); 
return error_code; 


return 0; 
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6.1 CEvtSysEventAdapter Class Reference 


#include <event-adapter.h> 


6.1.1 Detailed Description 


An Adapter for a legacy system should inherit this class and inherit its pure virtual functions. 


Public Member Functions 


+ virtual int onLoad ()=0 


virtual int onData ()=0 


virtual int onEvent (EvtSysEventSourceld_t src_id, const char xevent id, const GArray «properties, 
void xpriv_data)=0 


virtual int onUnload ()=0 


const string & name () 


Public Attributes 


* string m_name 


* intm fd 


Protected Member Functions 


e int publish (const char x*event_id,...) 


e int subscribe (const char xevent id, const char xfilter exp, CEvtSysEventAdapter xadapter, unsigned 
int *subscription_id) 


* int unsubscribe (unsigned int subscription id) 
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6.1.2 Member Function Documentation 
6.1.2.1 virtual int CEvtSysEventAdapter::onLoad () [pure virtual] 
onLoad() is called when an instance of CEvtSysEventAdapter is loaded (plugged-in). 


Sync (or) Async: 


This is a Synchronous API. 


6.1.2.2 virtual int CEvtSysEventAdapter::onData() [pure virtual] 
OnData() is called when there is data to be read from the Legacy System. 


Sync (or) Async: 


This is a Synchronous API. 


6.1.2.3 virtual int CEvtSysEventAdapter::onEvent (EvtSysEventSourceld_t src_id, const char * 
event id, const GArray x properties, void * priv data) [pure virtual] 


onEvent() is called when there is a LiMO event to be posted to the legacy system. The legacy system 
should subscribe to LiMo events to receive them. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[IN] sre id : Event source ID. 
[IN] event_id : This is an ID of the LiMo event being posted to legacy system. 


[IN] properties: Properties of the LiMo event being posted to legacy system. Properties of event are 
defined when the event is registered. See Section for details. 


[IN] priv data: The private data of the leagcy system can be passed to event handler using this pointer 
variable. Event handler can use this data for internal use. 


6.1.2.4 virtual int CEvtSysEventAdapter::onUnload ) [pure virtual] 


onUnload() is called when the instance of CEvtSysEventAdapter is unloaded. All the allocated memory 
from onLoad() must be released here. 


Sync (or) Async: 


This is a Synchronous API. 


6.1.2.5 const string& CEvtSysEventAdapter::name () [inline] 


Retreives the name of the Adapter 
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6.1.2.6 int CEvtSysEventAdapter::publish (const char x event_id,...) [protected] 


This function publishes event id to subscribers ie it converts a legacy system event to a LiMo event and 
posts the same to LiMo subscribers. 
Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[IN] event id This is an ID of the event or group of events. 


[IN] ... Publisher should pass event properties. The number of properties varies from each event to 
event. 


Returns: 
On success, zero is returned. On error, error value is returned. Its value may be one of those mentioned 


under Exceptions. 


Exceptions: 


EVTSYS ERROR EVENT INVALID EVENT ID 
EVTSYS ERROR EVENT INTERNAL TANSPORT 
EVTSYS ERROR EVENT FILTER EVALUATE 


6.1.2.7 int CEvtSysEventAdapter::subscribe (const char * event id, const char x filter exp, 
CEvtSysEventAdapter * adapter, unsigned int « subscription id) [protected] 


Application can subscribe to a specific event or a group of events using this API. To receive any event within 
a group of events, application should subscribe using event group ID, e.g. "System.State.Clamshell.x" is 
group ID for all Clamshell state events. 


Sync (or) Async: 


This is a Synchronous API. 


Parameters: 


[IN] event_id This is an ID of event or group of events. For example, "Clamshell opened" event can 
be represented like "System.State.Clamshell.Opened" and group of all Clamshell events can be 
represented like "System.State.Clamshell.x". +*(asterisk) is only allowed to appear after a dot. 
And after x nothing is allowed. Note that this is not a general wildcard mark. 


[IN] filter_expression It is a conditional statement that filters event. It filters out events which dont 
match filter condition. It should contain at least one property name which is event specific infor- 
mation. Property name(s) for each event_id is stored at Registry. In order to use no filter, NULL 
or empty string should be set. 

[IN] adapter It is a pointer to the Adapter of the legacy system subscribing for the event. 

[OUT] subscription_id This is a pointer to unsigned int. On successful subscription, ED will return 
subscription ID in this pointer which is to be used for unsubscription of the event. 


Returns: 


On success, zero is returned. On error, error_value is returned. Its value may be one of those mentioned 
under Exceptions. 
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Exceptions: 


EVTSYS_ERROR_EVENT_INVALID_EVENT_ID 
EVTSYS_ERROR_EVENT_INVALID_ARG 
EVTSYS_ERROR_EVENT_FILTER_NOT_ALLOWED_WITHOUT_PROPERTY 
EVTSYS_ERROR_EVENT_FILTER_NOT_ALLOWED_FOR_EVENT_GROUP 
EVTSYS_ERROR_EVENT_FILTER_EVALUATE 


6.1.2.8 int CEvtSysEventAdapter::unsubscribe (unsigned int subscription id) [protected] 
This function unsubscribes from the subscription for an event specified by subscrption_id. 


Parameters: 


[IN] subscription_id This is a subscription ID of event for which application wants to unsubscribe. 


Sync (or) Async: 


This is a Synchronous API. 


Returns: 


On success, zero is returned. On error, error_value is returned. Its value may be one of those mentioned 
under Exceptions. 


Exceptions: 


EVTSYS_ERROR_EVENT_INVALID_SUBSCRIPTION_ID 
EVTSYS_ERROR_EVENT_GCONF_SET_VALUE 
EVTSYS_ERROR_EVENT_GCONF_GET_VALUE 
EVTSYS_ERROR_EVENT_INTERNAL_TANSPORT 


6.1.3 Member Data Documentation 
6.1.3.1 string CEvtSysEventAdapter::m_name 


Event Adapter name 


6.1.3.2 int CEvtSysEventAdapter::m_fd 


File descriptor to be watched 


The documentation for this class was generated from the following file: 


e event-adapter.h 
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6.2 EvtSysEventProperty_t Struct Reference 


#include <limo-event-delivery.h> 


6.2.1 Detailed Description 


Event Property is a specific information to each Event. For example, Event "Sys- 
tem.State.BatteryLevel.Changed" has two Properties "BatteryLevel" and "ConnectedToCharger". 
The former is of integer type and the latter is of boolean type. 


Public Attributes 


* int type 
* union { 
gint32 i 
gboolean b 
double d 
char * s 
} value 


6.2.2 Member Data Documentation 
6.2.2.1 int EvtSysEventProperty_t::type 


Data type of property. This should be one of the followings: 


* DBUS TYPE INT32 


* DBUS TYPE BOOLEAN 


* DBUS TYPE DOUBLE 


* DBUS TYPE STRING 


6.2.2.2 gint32 EvtSysEventProperty t::i 


Signed integer. 


6.2.2.3 gboolean EvtSysEventProperty t::b 


Boolean variable. Should be 0 (FALSE) or 1 (TRUE). 


6.2.2.4 double EvtSysEventProperty t::d 


Double precision floating point. 
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6.2.2.5 char* EvtSysEventProperty_t::s 


Must be a NULL terminated string. 


6.2.2.6 union... ) EvtSysEventProperty_t::value 


The value is interpreted depending on the type field. 


The documentation for this struct was generated from the following file: 


* limo-event-delivery.h 
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6.3 EvtSysEventSourceld_t Struct Reference 


#include <limo-event-delivery.h> 


6.3.1 Detailed Description 


Event Subscription ID. On each subscription, ED will generate application-unique Subscription ID. Appli- 
cation uses this Subscription ID to unsubscribe from receiving Event. Event Source ID. name! is DBus 
service name. name2 is Event Adapter name. These names are chosen to be opaque so that we can easily 
change the underlying transport. 


Public Attributes 


int app_id 

int inst_id 

int pid 

char namel [EVENT SRC ID NAME SIZE MAX] 
char name2 [EVENT SRC ID NAME SIZE MAX] 


6.3.2 Member Data Documentation 
6.3.2.1 int EvtSysEventSourceld_t::app_id 


Application ID 


6.3.2.2 int EvtSysEventSourceld_t::inst_id 


Instance ID 


6.3.2.3 int EvtSysEventSourceld_t::pid 


Process ID 


6.3.2.4 char EvtSysEventSourceld_t::namel[EVENT_SRC_ID_NAME_SIZE_MAX] 


Internal Transport Name 


6.3.2.5 char EvtSysEventSourceld t::name2[EVENT SRC ID NAME SIZE MAX] 


Event Adapter name. Event Adapter is for supporting legacy services 


The documentation for this struct was generated from the following file: 


* limo-event-delivery.h 
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Chapter 7 


File Documentation 


7.1 ComponentOverview.h File Reference 


7.1.1 Detailed Description 


Component Programming Interface Overview Header Template for Doxygen. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 
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